# resume_filter\matcher\base_matcher
# 定义所有matcher的基类

# 文件：matcher/base_matcher.py

from abc import ABC, abstractmethod
from typing import Dict, Any

class BaseMatcher(ABC):
    """
    匹配器基类，定义所有matcher必须实现的接口规范。
    负责输入结构化简历和岗位描述，输出标准化匹配结果。
    """

    @abstractmethod
    def match(self, resume: Dict[str, Any], jd: Dict[str, Any]) -> Dict[str, Any]:
        """
        核心匹配函数。接收结构化简历和职位描述信息，
        返回匹配结果的字典，必须包含但不限于以下字段：
          - total_score: float，总体匹配分数，范围通常[0,1]
          - details: dict，分项匹配分数或详细信息
          - passed: bool，是否通过预设阈值判定

        :param resume: 结构化简历数据（dict）
        :param jd: 结构化岗位描述数据（dict）
        :return: 标准化的匹配结果字典
        """
        pass

    def _check_inputs(self, resume: Dict[str, Any], jd: Dict[str, Any]):
        """
        可选的输入校验方法，确保输入结构合理，避免下游错误。
        """
        if not isinstance(resume, dict):
            raise TypeError("resume 参数应为字典类型")
        if not isinstance(jd, dict):
            raise TypeError("jd 参数应为字典类型")

    def run(self, resume: Dict[str, Any], jd: Dict[str, Any]) -> Dict[str, Any]:
        """
        对外统一调用接口，包含输入校验和异常捕获，
        便于外层调用和日志管理。

        :param resume: 结构化简历数据
        :param jd: 结构化岗位描述数据
        :return: 匹配结果字典
        """
        try:
            self._check_inputs(resume, jd)
            result = self.match(resume, jd)
            # 结果格式检查（可选）
            assert "total_score" in result and "passed" in result and "details" in result
            return result
        except Exception as e:
            # 统一错误处理，可扩展日志打印
            return {
                "total_score": 0.0,
                "details": {},
                "passed": False,
                "error": str(e)
            }
